Application program interface for message routing and management system

ABSTRACT

Transmission of messages composed on one or more input devices to a single or multiple recipients by means of one or plural communication modes is facilitated. Such communication modes may include conventional or wireless telephone, facsimile transmission, pager, e-mail, postal mail or courier. An application program interface (API) mediates between remote applications requesting messaging functions and a message server that actually implements these functions. The API is capable of processing high-volume requests for message routing, status information, and various other functions on an automated basis, enabling businesses to make routine use of these functions.

RELATED APPLICATION

This application claims the benefits of U.S. Provisional ApplicationSer. No. 60/189,145, filed on Mar. 14, 2000.

FIELD OF THE INVENTION

The present invention relates to communication services, and inparticular to delivery of messages to selected recipients through one ormore specified communication modes.

BACKGROUND OF THE INVENTION

Thanks to improvements in technology and widespread consumer interest,once-exotic forms of communication have become commonplace, and todaythe average consumer has access to a broad array of communicationsservices. The Internet and wireless telephony, once the preserve of anelite few, now routinely supplement traditional telephone services andare frequently supplied by the same carriers. Even inexpensive homecomputers now include facsimile capability. Businesses employing mobileemployees can furnish them with economical pagers that incorporateadvanced features, such as text transmission and Internet access.

The sheer proliferation of communication options, while greatlyimproving access and convenience, has engendered problems as well. Theexistence of a communication channel does not ensure that the recipientof a message will be “listening” to that particular channel at a giventime, yet the sender of a message has no way to know this. Indeed, morechannels of communication traffic mean more demands on the attentions ofpotential recipients, who, feeling besieged by the assault of e-mail,voice mail, pages, etc., may simply inactivate some communicationdevices at different times. Message senders, therefore, are faced withthe choice of risking non-delivery of their messages, or painstakinglyre-transmitting a message on every possible mode of communicationmodality.

It may also be difficult to transmit the same message to multiplerecipients. While a single e-mail message, sent once, can reach anunlimited number of destinations, phone messages must be repeated foreach call. Moreover, different recipients may have access to differenttypes of communication channels; perhaps some recipients can be reachedefficiently only by e-mail, others by fax, and still others by page.

The integration of communication input devices also raises the prospectof messages having multiple forms of content. Today, a single messagemay include input from a variety of sources (e.g., voice and text);transmitting such a message by traditional means may be quitecumbersome, involving multiple separate transmissions that must becoordinated or difficult “packaging” of the different inputs into asingle message.

U.S. Ser. No. 09/496,170, filed on Feb. 1, 2000 and entitled Multi-ModeMessage Routing and Management (the entire disclosure of which is herebyincorporated by reference) addresses these difficulties and discloses,inter alia, a facility for transmission of messages composed on one ormore input devices to a single or multiple recipients by means of one orplural communication modalities. Such communication modalities mayinclude, for example, conventional or wireless telephone, facsimiletransmission, pager, e-mail, postal mail or courier. Thus, a message maybe directed to a single recipient via multiple modalities, such ase-mail and fax, in order to ensure the earliest possible receipt of themessage; or may be directed to multiple recipients by a single modalityor by different modalities (e.g., some recipients receive the message bye-mail, others by fax, others by phone). The facility may be configuredto respond to defined “escalation” rules that specify conditions underwhich different delivery modalities may be sequentially employed. Forexample, the rules may specify that if there is no response to ane-mailed question within an hour, the recipient is to be telephoned.Moreover, in addition to alternative transmission modalities, theescalation rules may specify alternative recipients (as well asalternative modalities for those recipients). The escalation rules mayalso specify default contact methods, which may apply to specificindividuals or to lists of recipients.

The invention disclosed in the '170 application may includefunctionality for determining whether a message has been received (e.g.,telephone and e-mail polling), as well as automatic sender notificationupon confirmation of receipt. Moreover, in addition to monitoringmessages in order to confirm their receipt, the invention may facilitaterecipients' responses. In this way, the invention can orchestratemulti-question surveys utilizing multiple communication modes; forexample, individuals contacted directly can respond immediately, whileothers can respond later in accordance with instructions delivered tothem—e.g., via a web site or by calling a toll-free number.

The invention disclosed in the '170 application supports messages havingembedded questions that call for response by the recipient. Suchresponses, when received, may be communicated to the message senderand/or accumulated.

Also facilitated by the invention disclosed in the '170 is scheduling ofmessage delivery, on a mode-by-mode basis where appropriate. Schedulingmay include delivery at a particular time or within a designated timewindow, or may involve preventing delivery during specified “black-out”periods. In some embodiments, scheduling may be automatic and based onconsiderations such as the recipient's time zone and the form ofcommunication (e.g., to avoid awakening the recipient by telephone).

However, the '170 application contemplates a system in which customers'client computers communicate via the World Wide Web (the “web”) with aserver implementing the foregoing functions. In other words, theinteraction is essentially manual and stepwise in nature, with customersselecting options and indicating preferences in an interactive session.This model is generally unsuited to business applications requiring moreautomated, high-volume access to messaging functions.

DESCRIPTION OF THE INVENTION

Brief Summary of the Invention

The present invention provides an application program interface (API)facilitating interaction, generally (although not necessarily) via theInternet, with a message-handling facility such as that disclosed in the'170 application. In accordance with the invention, applicationprogrammers utilize a markup language (preferably XML-derived) toconfigure applications for compatibility and communication with themessage-handling facility. The API is capable of processing high-volumerequests for message routing, status information, and various otherfunctions on an automated basis, enabling businesses to make routine useof these functions.

Indeed, the range of business-to-business and business-to-consumerorganizations that can benefit from flexible messaging services isvirtually limitless. For example, an airline may obtain contactinformation from passengers when tickets are purchased. Should a flightbe delayed or cancelled, the airline can generate a single notificationfor transmission to all passengers via the messaging facility; as theflight time approaches, efforts to reach passengers not yet contactedcan be intensified according to defined escalation rules. Similarly, aclub or other organization can send out notices of meetings, receiveconfirmations and preferences from members, and alert them to changesusing the messaging facility by means of the API. The message need bewritten and transmitted by the organization only once; all remainingoperations, from bulk re-transmission to collecting and organizingresponses, are performed automatically.

In accordance with the invention, a message server comprising aplurality of modalities for transmitting messages is associated with anAPI. An application, typically implemented on a remote server, isconfigured to receive a message and a designation of one or moretransmission modalities, and is further adapted for interaction with theAPI. The API comprises stored instructions supporting the interaction.Upon receiving the message and the designation from the applicationserver, the API causes the message server to transmit the messageaccording to the designation.

BRIEF DESCRIPTION OF THE DRAWINGS

The foregoing discussion will be understood more readily from thefollowing detailed description of the invention, when taken inconjunction with the accompanying drawings, in which:

FIG. 1 schematically represents the environment of the invention; and

FIG. 2 schematically illustrates the components of the API and its modeof interaction.

DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENTS

1. Technical Context

The functions of the messaging system are implemented by a server 125,which may be realized as a single workstation or as a network of servercomputers, depending on the activity level and included functionality.For explanatory purposes, server 125 is represented as a single machinethat includes a network interface 127 continuously connected to theInternet. Network interface 127 and the other internal components ofserver 125 intercommunicate over a main bidirectional bus 130 (which maybe a physical bus in a single hardware device, or can instead representa network such as a LAN or a WAN). The main sequence of instructionseffectuating the functions of server 125 and facilitating interactionamong customers, server 125, the Internet, and other modes ofcommunication reside on a mass storage device (such as a hard disk oroptical storage unit) 132 as well as in a main system memory 134 duringoperation. Execution of these instructions and effectuation of thefunctions of server 125 is accomplished by a central-processing unit(“CPU”) 136.

A group of functional modules that control the operation of CPU 136 andperform the operations of server 125 is shown conceptually as located insystem memory 134; once again, however, it should be stressed that thisorganization is for explanatory purposes. The various modules andservers may indeed be implemented as active processes running on asingle machine, but functionality may instead be distributed amongmultiple machines (or processors within a single machine), once againdepending on the activity level and included capabilities.

An operating system 140 directs the execution of low-level, basic systemfunctions such as memory allocation, file management, and operation ofmass storage devices 132. At a higher level, a control block 142,implemented as a series of stored instructions, manages interactionamong the various functional components of the server and ensures properrouting of data thereamong.

Although server 125 may be capable of communicating directly withcustomers by means of the web and electronic mail, as explained in the'170 application, the present application is concerned primarily withhardware-to-hardware communications. Accordingly, an API 145 receivesand processes communications from external sources, and transmits properresponses to those sources, via network interface 127. API 145represents a programmatic interface for direct connection toappropriately configured third-party applications. The pattern ofinteraction with the external source, including the content oftransmissions thereto, is handled by a transaction server 150.Transaction server 150 has access to various databases, collectivelyindicated at 152; these databases, discussed in greater detail below,are ordinarily stored on devices 132 and accessed as necessary.Depending on the requests received by API 145, transaction server 150causes messages to be assembled and transmitted to designated contacts,and retrieves and assembles information for transmission to outsideinquiries. Credit-card validation and billing for services are handledby a billing server 160.

The various functions performed by server 125, which result in differentpatterns of interaction with customers, will now be described.

1.1 Media Conversion and Basic Message Transmission

A series of media servers, collectively indicated at 175, represent theinterface servers that format messages for transmission; these messagesmay be in the form of voice, text (for transmission by e-mail, web orpostal mail), or other desired format. Messages and media designationsare received from remote applications via API 145, and once transactionserver 150 has received sufficient commands and content to fully specifya message (i.e., the message body, the recipient(s), desired deliverymethods, and message options such as delivery scheduling and/orescalation rules), a message “job” is created and stored in a database152. The job is passed to a job queue server 165, which is responsiblefor implementing and scheduling all message jobs.

At this point, the message remains in the format in which it wasgenerated. As noted previously, however, server 125 is capable ofreceiving messages, via the interface servers, in one format andtransmitting them in a different, customer-selected format. Thefunctions of media conversion and message assembly are performed by aseries of message delivery servers, collectively illustrated at 167,dedicated thereto. The appropriate message delivery server 167 convertsmessages to the specified format and causes their transmission, via thedesignated communication medium, by means of a corresponding devicedriver selected from among a suite of drivers. The drivers operate aseries of transmission devices, which include network interface 127 fore-mail and/or web-based message delivery; a telephone interface 170 formessage transmission by telephone, facsimile, pager, or handheldwireless device (although it should be noted that pager and wirelesstransmission can occur through network interface 127); and adocument-generation module 172 for message transmission by postal mailor overnight courier.

The timing of message transmission is governed by job queue server 165.In response to the customer's authorization to send a message, job queueserver 165 triggers the conversion and transmission operations justdiscussed. Job queue server 165 also contains (or, as shown forillustrative purposes, communicates with) a scheduling module 180, whichcan orchestrate transmission of messages at customer-specified timesbased on the computer's internal clock.

Server block 165 may contain a text-to-speech conversion module,enabling customer-provided text to be transmitted by voice to therecipient by means of telephone interface 170. Conversely, telephonyserver 175 may be configured to respond to spoken customer commands,allowing the customer to compose and address a message by telephone(i.e., by communicating with server 125 by means of telephone interface170).

In still more complex operational modes, server 125 may facilitatecatenation of message—either as separate segments of the same format, oras segments encoded in different formats. In the case of audio messages,for example, a message delivery server 167 may append an audio “header”(typically a so-called “professional prompt”) and a “trailer” to thecustomer's message. Thus, when the recipient answers the telephone, theheader portion of the message may tell him that he is about to receive amessage from the customer, and the trailer portion may facilitateresponse (as explained in further detail below).

1.2 Confirming Message Receipt

Any of a variety of techniques can be used to assess whether and when amessage is received. Many e-mail systems natively support receiptconfirmation. Alternatively, a URL can be embedded in the message; whenthe recipient receives the e-mail and clicks on this URL, receipt isautomatically recorded. Moreover, the URL-specified web page may containquestions inviting response by the recipient, who thereupon transmitsthe web page back to server 125.

Hard-copy deliveries can be tracked through the courier or by means of afollow-up telephone call to the recipient, while for telephone messages,the recipient can be asked to press a number to confirm receipt. In thecontext of telephone messages, it may be useful to detect whether aperson or an answering machine has answered the phone. Thisdetermination can be used, for example, to select a proper audio headeror even to choose between alternative messages, which may differdepending whether the message is delivered to the recipient or arecording device; an answering machine, obviously, would not be asked topress a number to confirm receipt, nor would delivery typically beconfirmed to the sender if the message was left on an answering machine.To implement answer detection, telephony server 147 is programmed tomonitor the level of noise on the line once a connection is established,distinguishing between a “silence” noise level and a “speech” level. Ifan individual answers, he or she will typically issue a short greeting;that is, the signal pattern of a human answer is a short speech signalfollowed by silence. An answering machine, by contrast, will generallyissue a long greeting (“Hello, you have reached the Smiths . . . ”).Based on the observed lengths of a sustained speech signal and anensuing silence, telephony server 147 forms an initial guess as towhether a person or a machine has answered. If a person is guessed,telephony server 147 will play the audio header that prompts theanswerer to press a touch-tone key, and if the proper touch-tone pulseis not detected, server 147 may revise its guess and assume that it iscommunicating with an answering machine.

1.3 Message Scheduling

It may not be appropriate to transmit messages by certain modes duringparticular time periods at the recipient's location. These “blackout”time periods may be established automatically by server 125, or may bedesignated by the customer or the recipient. Via API 145, an externalapplication may indicate blackout time periods for a particular message,or may permanently designate such periods for particular contacts (andparticular communication modalities). Most commonly, permanentlydesignated blackout periods are used to prevent messages from being sentby telephone or pager during times when the recipient is generallylikely to be asleep or away from the communication modality.Message-specific blackout periods may be utilized by message sendersfamiliar with the recipient's immediate schedule, or who do not wish topermanently establish blackout periods.

Conversely, the external source may specify particular allowed timewindows within which a message must be delivered. Once again, these maybe established permanently for particular contacts or “on the fly” forspecific messages.

Time-zone scheduling may be employed automatically. For example, if thecustomer authorizes immediate message delivery at a time that would belate at night where the recipient is located, or schedules messagedelivery for such a time, transaction server 150 may cause the customerto be prompted with this information and asked to confirm or rescheduledelivery.

1.4 Escalation

Rather than send a message to a prospective recipient redundantly viamultiple communication modalities, transaction server 150 may beconfigured to allow the specification of escalation rules for sequentialtransmission as necessary. The external application selects a pluralityof communication modalities and/or contacts, and criteria in the form ofrules governing their use. Typically, an escalation rule will specifyresort to a different communication modality (or a different recipient)if delivery of the message is not confirmed by a specified time, orwithin a specified period, using the current communication modality.

Like scheduling restrictions, escalation rules may be definedpermanently for a contact (and stored, along with “address book”information pertaining to that contact, in database 152 b) or mayinstead be defined for a particular message. Default message modalitiesand permanent escalation rules are particularly useful in the context ofdistribution lists, since the external application can simply enter amessage and leave it to server 125 to deliver it to every person on aselected distribution list in accordance with each contact's escalationrules. On the other hand, message-specific escalation rules may bedesignated for particular messages transmitted to API 145.

To implement the escalation rules, the time period specified in a rulerelevant to the initial message transmission is sent to scheduler 180.At the end of that time period following transmission, transactionserver 150 determines whether the message has been received in themanner described above. If not, the escalation rule (defined in database152 b or in the transaction record for the particular message) isexecuted, and the message re-transmitted by a different modality. Iffurther escalation rules remain for the message, the appropriate timeperiod is once again provided to scheduler 180, and the flow sequencerepeated.

2. An Exemplary Application Program Interface

With reference to FIGS. 1 and 2, external sources such as a server 190generate requests for messaging functions and status information, andtransmit these to server 125 via a computer network, such as theInternet, for processing. FIG. 2 illustrates in greater detail the roleand basic components of API 145. Requests are actually generated by anapplication 210 running as an active process on server 190. Application210 formats these requests in the syntax allowed by API 145. Requestsreceived by API 145 from application 210 are analyzed by a parser 210,which interprets the request and causes the various server modules ofserver 125 to take appropriate action. The server modules may generatedirect responses to the requests or provide status information fortransmission to application 210. A converter 220 places such informationinto statements conforming to the API syntax prior to transmission.

Preferably, the API syntax conforms to the conventions of XML, using“tags” to characterize elements such as statements and field data. A tagsurrounds the relevant element(s), beginning with a string of the form<tagname> and ending with </tagname>. Thus, parser 215 can be (or bebased on) a conventional XML parser.

The contents of a communication to or from API 145 take the form of a“document,” which contains an identifying tag and either a “Request”(for documents generated by application 210) or a “Response” (fordocuments that API 145 returns to applications 210). Document elementsare hierarchically organized into objects. Each object specifies thecontents of fields associated with the object, and may also contain oneor more nested, hierarchically inferior objects; this structuremaintains the organization of information, facilitates movement ofinformation in meaningful packages, and allows for re-use of informationwithout explicit repetition.

At the highest hierarchical level, “Super Objects” define thecommunication as a Request or a Response, and contain one or more “MajorObjects.” The Major Objects specify key functional elements of messagingactivities, defining the relevant user accounts and the nature of thedesired message functions, and may contain sub-objects and/or entriesfor various fields within the Major Objects. Fields contain information,such as character strings or numbers, relevant to the objects containingthem.

The overall organization of a preferred implementation of API 145appears in summary form below; following the summary, the variousobjects and fields are described in greater detail. It should beunderstood that this API is illustrative only.

TABLE 1 Basic API Organization I. Super Objects: contain required fieldsand one or more major objects A. Request (fields:) i) UserName ii)Password iii) Domain iv) OEMId v) OEMPassword vi) RequestType B.Response: same fields/objects as request + errors, warnings II. MajorObjects: required elements of documents, may contain sub- objects andfields A. Member (fields:) i) Command ii) Id iii) FirstName iv) LastNamev) Company vi) UserName vii) Password viii) AllowNotices ix) DialinId x)Dialin Password Member (subobjects:) i) Contact Method ii) Billing(fields: Id; Billing Plan; CurrentBalance) iii) Credit Card (fieldsyou'd expect) B. Contact (subobjects:) i) Contact Method (fields:) a. Idb. Transport c. Qualifier d. Ordinal e. PhoneNum, FaxNum, PagerNum f.Access Code g. Email Address h. Street1 i. Street2 j. Suite k. City l.State m. Zip n. Country ii) Contact MethodRef (fields:) a. Id b.FirstName, LastName, Company c. Transport, Qualifier, Ordinal d.AllowMultiple Contact (fields:) i) Command ii) Id iii) Prefix (optional)iv) First Name, Middle Name, Last Name v) Company (optional) vi) Title(optional) C. Distribution List (fields:) i. Command (create, replace,append, delete, remove) ii. Name iii. Description iv. Id D. Job(fields:) i. Id ii. Charges Job (subobjects:) i. Message (fields:) A.Subject B. Template (optional) C. Id D. Date Message (subobjects:) A.MessageArg Objects: series of Name/Value tags: 1) SENDER 2) BODY 3)ASK_YESNO_QUESTION 4) QUESTION_TO_ASK 5) EMAIL_ADDR B. DeliveryTimeObjects C. DeliveryTimeModifier Objects ii. Contact (to specify one-timerecipient of message) iii. Delivery Request (elements:) A.DeliveryOptions field (in) B. Contact MethodRef sub-object DeliveryRequest (returned elements:) A. ContactMethod B. Contact C. Delivery(fields:) 1) Id 2) Timestamp 3) Duration 4) Status (Not Sent, Sent,Failed, Cancelled, Cancel Pending) 5) Details (Bad Address, DeliveryAddress is unreachable, No Answer, Busy, Answering Machine (assumed),Answering Machine, Maximum Delivery Attempts Exceeded, Acknowledged,Modem, Hangup, Callback Later, Internal Error 6) Size 7) Cost D.DeliveryRequest fields (out) 1) Id 2) EstDuration 3) EstSize 4) Status5) Details 6) Completed E. Range (fields:) i. Object (i.e., type ofobject trying to look up) ii. Type iii. Start iv. End

Every transmission to API 145 requires a Request, which will generate aResponse from API 145 (and the server modules with which it functions).The Request must identify one or more valid “members” by means ofUserNames. A request contains the following required fields:

TABLE 2 Request Fields Allowed Field Description In/Out Values ExampleUserName Login name that identifies the member In String<UserName>RalphW </UserName> Password Password for the member assignedby the In String <Password>abc123 domain </Password> Domain Identifier(generally identifies the In String <Domain>POETS</Domain> company ororganization to which the member belongs) OEMId The domain ID(identifies company or In <OEMId>kkk52057kk organization) </OEMId>OEMPassword The client password In <OEMPassword> OEMPassword</OEMPassword> RequestType Requests one of the following actions Invalidate <RequestType>validate Validate (Check all of the fields and subcommit </RequestType> objects for syntax and validation errors, lookupdoes not take any additional action) Commit (Put the document indatabase, and initiate requested actions) Lookup (Find objects in thedatabase, based on specified criteria; used with the Range object only)

(In this and other tables, the In/Out column indicates whether the fieldis used in a Request (in), in a corresponding Response (out), or inboth.)

In addition to fields, the Request will generally contain one or moreMajor Objects. Typical actions include: send a message to specifiedrecipients; add/edit/delete member, distribution list, contactinformation; look up the status of a job; send a billing inquiry. Thefollowing represents a typical Request (with the Contact Object,discussed in greater detail below, indicated but not actuallyspecified):

-   -   <Request>        -   <UserName>RalphW</UserName>            -   <Password>abc123</Password>            -   <Domain>POETS</Domain>            -   <OEMId>OEMId</OEMId>            -   <OEMPassword>OEMPassword</OEMPassword>            -   <RequestType>validate</RequestType>    -   [Contact Object]    -   </Request>

The Response is generally returned with the same objects that wereincluded in the Request; if, however, the Request asks for information(e.g., a request for message status or for billing information), someobjects or fields may be added or changed. In addition, the Responsewill contain Errors and Warnings fields as appropriate:

TABLE 3 Errors and Warnings (Response Fields) Allowed Fields DescriptionIn/Out Values Example Errors Set to the number of errors discovered OutUnsigned <Errors>2</Errors> while processing the major objects integerincluded in the Request Warnings Set to the number of warnings (a lessOut Unsigned <Warnings>0</Warnings> severe error) discovered whileinteger processing the major objects included in the Request

Errors and Warnings are described in greater detail below.

The following represents a typical Response (with the Contact Objectonce again indicated but not actually specified):

-   -   <Response>        -   <UserName>RalphW</UserName>        -   <Password>abc123</Password>        -   <Domain>Poets, Inc. </Domain>        -   <OEMId> OEMId</OEMId>        -   <OEMPassword> OEMPassword</OEMPassword>        -   <ResponseType>validate</ResponseType>        -   <Errors>2</Errors>        -   <Warnings>0</Warnings>    -   [Contact Object]    -   </Response>

Requests and Responses specify one or more Major Objects as follows:

TABLE 4 Major Objects Major Object Description Member User-level loginthat identifies a user account (end user or member) Contact Person ororganization to which a message may be sent Distribution List A group ofcontact methods (for example, phone number, pager number, email address)to which a message may he sent Job Message to one or more contacts usingone or more contact methods Range Used to look up other objects based onspecific search criteria; for example, to look up a job by Id, or jobssent on a certain date, or all contacts from the same organization

Each Major Object contains zero or more fields and sub-objects, whichmay themselves contain additional sub-objects and/or fields. The variousMajor Objects will now be described in detail.

Major Objects—Member: generally an end user of the messaging service.

Major Objects—Member—Fields: The Member object has the following fields:

TABLE 5 Memeber Major Object Fields Allowed Fields Description In/OutValues Example Command Requests one of the following In create<Command>create</Command> (Required) actions: update Create (Add a newMember remove object) Update (Modify Member object information) Remove(Remove a Member object Id Unique identifer assigned in a CreateAlphanumeric <Id>k5j34kd</Id> Response to a Request to create a (Out)string Member object Update (In) Remove (In) FirstName The member'sfirst name In String <FirstName>Virginia</FirstName> (Required) with a32 character limit LastName The member's last name In String<LastName>Woolf</LastName> (Required) with a 32 character limit CompanyThe member's company affiliation In String <Company>Hogarth (Optional)with a 32 Press</Company> character limit UserName The member's login;must be In String <UserName>VirginiaW</UserName> unique within thedomain with a 32 character limit Password The member'secret password InString <Password>abc123</Password> with a 32 character limitAllowNotices Marks this member as being In “True” (to <AllowNotices>trueinterested in receiving receive allow): </AllowNotices> periodicmailings specific to this otherwise, domain “False” DailinId This is away for the member to In Numeric <DialinId>9146445543</DialinId>identify himself when calling into string a voice response (automatedtouch tone telephone) system DialinPassword Serves as a PIN for thevoice In Numeric <DialinPassword>1234 response system string</DialinPassword>

Major Objects—Member—Sub-objects: In addition, the Member objectcontains the following required sub-objects:

Major Objects—Member—Sub-objects—Contact Method: specifies communicationmode (e-mail, telephone, etc.) and contact information (e-mail address,telephone number, etc.) specific thereto. Contact Method sub-objects arefurther described below in connection with the Contact Major Object.

Major Objects—Member—Sub-objects—Billing: specifies the billing plan anddetails necessary to bill the member (such as a credit-card number). Theobject also describes the current account status. The following tablesets for the required fields for the billing sub-object:

TABLE 6 Member Major Object Billing Sub-object Allowed FieldsDescription In/Out Values Example Id Unique identifier Out<Id>k1231bj4</Id> Billing Plan Indicates which plan the member is In<BillingPlan>kkk33kkkk using (pay-as-you-go, prepaid, both </BillingPlan> using a credit card) CurrentBalance Current balance in US dollarsas a Out <currentBalance>15.22 floating point number </CurrentBalance>

The billing sub-object, in turn, contains a Credit Card sub-object, thefields for which are set forth in the following table:

TABLE 7 Member Major Object Billing Sub-object Credit Card Sub-objectAllowed Fields Description In/Out Values Example FirstName, Name as itIn Each name field <FirstName>Virginia<1/FirstName> MiddleName, appearson the is a string with a <MiddleName>L.</MiddleName> LastName creditcard 32-character <LastName>Woolf</LastName> limit CreditCard RequiredIn Number as it <CreditCardNumber>5123123412341233 Number appears on the</CreditCardNumber> credit card Expiration Expiration In Two-digit<ExpirationMonth>8</ExpirationMonth> Month month as it number as itappears on the appears on the credit card card Expiration YearExpiration year In Four-digit <ExpirationYear>2001</ExpirationYear> asit appears on number the credit card StreetAddress1 First line of the InFirst line of <StreetAddress1>25 Hollywood street address billingaddress St.</StreetAddress1> for this card for this card StreetAddress2Second line of In Second line of <StreetAddress2>Hogarth Press thestreet billing address Inc.</StreetAddress2> address for this for thiscard card City City of billing In City name <City>Los Angeles</Cityaddress for this card State State of billing In Use two-letter<State>CA</State> address for this state card abbreviation Zip Zip codein the In Zip codes can be <Zip>90210-1234</Zip> US, postal code eitherfive or outside nine digits; hyphen is optional Country Country InCountry name <Country>USA</Country>

The following is an example of entire Member Object:

-   <Member>    -   <Command>create</Command>    -   <FirstName>Ralph</FirstName>    -   <LastName>Emerson</LastName>    -   <Company>Poets R Us</Company>    -   <UserName>RWE</UserName>    -    Password>MyPassword</Password>    -    <DialinId>12345</DialinId>    -   <DialinPassword>12345</DialinPassword>        -   <ContactMethod>            -   <Transport>email</Transport>            -   <Qualifier>none</Qualifier>            -   <EmailAddress>ralph@Poets.com</EmailAddress>        -   </ContactMethod>        -   <ContactMethod>            -   <Transport>phone</Transport>            -   <Qualifier>office</Qualifier>            -   <Ordinal>0<Ordinal/Ordinal>            -   <PhoneNum>617-123-4567</PhoneNum>        -   </ContactMethod>        -   <Billing>            -   <BillingPlan>kkk33kkkk<BillingPlan>            -   <CurrentBalance>1.00<CurrentBalance>                -   <CreditCard>                -    <FirstName>Ralph</FirstName>                -    <MiddleName>Waldo</MiddleName>                -    <LastName>Emerson</LastName>                -    <CreditCardType>Master Card</CreditCardType>                -    <CreditCardNumber>5123123412341233</Cre                    ditCardNumber>                -    <ExpirationYear>2001</ExpirationYear>                -    <ExpirationMonth>8</ExpirationMonth>                -    <StreetAddress1>1313 Mockingbird                    Lane</StreetAddress1>                -    <StreetAddress2>Poets R Us</StreetAddress2>                -    <City>Warren</City                -    <State>MA</State>                -    <Zip>01810</Zip>                -    <Country>USA</Country                -   </CreditCard>            -   </Billing>    -   </Member>

Major Objects—Contact: identifies an individual to whom a message may besent. A Contact Object contains one or more Contact Method sub-objects(described below), each of which identifies a way to reach theindividual. Contact and Contact Method information may or may not bestored in a member's Address Book (i.e., the a collection of a member'sContacts and their associated Contact Methods stored in database 152 b).Thus, a Contact Major Object may be created to be stored in an AddressBook, or for one-time use.

Major Objects—Contact—Fields: The Contact object has the followingfields:

TABLE 8 Contact Major Object Fields Fields Description In/Out AllowedValues Example Command Requests one of the In create<Command>create</Command> following actions: update Create (Add a newremove Contact object) NOTE: (This field is Update (Modify Contactrequired only when the object information) Contact is to be used asRemove (Remove a a major object; that is, so Contact object) the contactis stored in the Address Book for reuse.) Id Required field that In (forSupplied after a contact <Id>k5j34kd</Id> identifies the member updatehas been created. when the Command field and is used to update orremove) remove the Contact. Prefix Indicates the contact's In String<Prefix>Mr.</Prefix> (Optional) preferred title, for example, Mr., Ms,Dr. First Name The contact's first, middle In Each name field is a<FirstNamex>William Middle Name and last names; first and String with a32- </FirstName> Last Name last names are required character limit<MiddleName>S. </MiddleName> <LastName>Shakespeare </LastName> CompanyIndicates the name of the In String with a 32- <Company>Globe Theater,(Optional) company or organization character limit Inc.</Company> withwhich the contact is affiliated Title Indicates a job title for InString with a 32- <Title>Director</Title> (Optional) the contactcharacter limit

Use of the Command field ensures that the Contact Object will be storedin the Address Book of the member with which it is associated. When theContact Object is nested as a sub-object of a Job object (describedbelow), the contact information will not be stored in an Address Book.

The following represents a typical Contact Object (with Contact Methodobjects indicated but not actually specified):

-   <Contact>    -   <Prefix>Mr.</Prefix>        -   <FirstName>William</FirstName>        -   <MiddleName>L.</MiddleName>        -   <LastName>Shakespeare</LastName>        -   <Company>Globe Theater, Inc. </Company>        -   <Title>Director</Title>        -   [ContactMethod Objects]-   </Contact>

Major Objects—Contact—Sub-objects—Contact Method: as explained above,this object specifies the manner in which a member may be contacted. AContact Method sub-object may contain some or all of the

TABLE 9 Contact Method Sub-object Fields Fields Description In/OutAllowed Values Example Id Identifies this In or Out Required based onthe logic <Id>k5j34kd</Id> Contact Method for the parent Contact object.object NOTE: The Contact Method object does not have a Command field;rather, it is nested within a Contact object that does have a Commandfield. Transport Indicates In Phone <Transport>email</Transport>(Required) delivery Fax method Pager Email Mail Qualifier Indicates theIn Home <Qualifier>cell</Qualifier (Required) type of phone or Home2 faxOffice Office2 Cell NOTE: Member is a legal value for Qualifier onlywhen used in a Member object. Ordinal A counter that In Unsignedinteger, Only <Ordinal>0</Ordinal> allows entry of required if there ismore than more than one one of a particular kind of exact type ofcontact method (home 0, contact method. home1). For example, for yourfirst phone number, the ordinal would be “0”; for the second, theordinal would be “1” PhoneNum Telephone In Typical phone number with<PhoneNum>212-123- FaxNum number for area code (no “1” for long4567</PhoneNum> PagerNum phone, fax, distance needed); for example<FaxNum>2121234568</FaxNum> pager 2121234567; hyphen is<PagerNum>800-456- optional 4567</PagerNum> Access Access number In Usedonly when the pager <AccessCode>77325#</AccessCode> Code for a pagerservice requires the caller to enter an identifying touch tone string(sometimes, ending with the pound sign or asterisk) before entering acallback number Email Email address In Typical email address<EmailAddress>!<[CDATA[jkrowling Address @bloomsbury.com]]></EmailAddress> Street1 Street address In String with 32 character limit<Street1>100 Park Avenue</Street1> Street2 Second line of In String with32 character limit <Street2>Waldorf Astoria address Hotel</Street2>Suite Suite number, if In String with 32 character limit <Suite>TowerSuite 1400</Suite> applicable City City In String with 32-characterlimit <City>New York</City> State State In Two-character abbreviation<State>NY</State> Zip Zip code in the In String <Zip>10021</Zip> US;postal code elsewhere Country Country In String with 32 character limit<Country>USA</Country>

To denote a member's primary e-mail address, for example, the followingsyntax is employed:

-   -   <Contact Method>        -   <transport>email</transport>        -   <qualifier>member</qualifier>        -   <EmailAddress>ralph@poets.com</EmailAddress>    -   </Contact Method>

The following example illustrates addition of a new contact to anAddress Book:

-   <Contact>    -   <Command>create</Command>        -   <FirstName>Albus</FirstName>        -   <LastName>Dumbledore</LastName>        -   <Company>Hogwarts School for Witchcraft and            Wizardry</Company>        -   <Title>Headmaster</Title>    -   <ContactMethod>        -   <Transport>phone</Transport>        -   <Qualifier>cell</Qualifier>        -   <PhoneNum>9785551234</PhoneNum>    -   </ContactMethod>    -   <ContactMethod>        -   <Transport>pager</Transport>        -   <PagerNum>8885551234</PagerNum>        -   <AccessCode>1030#</AccessCode>    -   </ContactMethod>-   </Contact>

Major Objects—Contact—Sub-objects—Contact MethodRef: once a ContactMethod has been created and stored, it may be referred to using apointer called a Contact MethodRef. The pointer contains the ContactMethod's Id, or a combination of fields that will uniquely identify thatContact Method.

A Contact MethodRef sub-object may contain some or all of the followingfields:

TABLE 10 Contact MethodRef Sub-object Fields Fields Description In/OutAllowed Values Example Id Identifies this Contact In Exsisting ContactMethod ID <Id>k5734kd</Id> Method object FirstName These fields are allIn Existing Contact fields <FirstName>Ron</Firstname> LastName from theContact <LastName>Weasley</Lastname> Company object<Company>Hogwarts<Company> Transport These fields are all In ExistingContact Method <Transport>email</Transort> Qualifier from the Contactfields <Qualifier>home</Qualifier> Ordinal Method sub-object<ordinal>0<Ordinal> AllowMultiple In true (default value)<AllowMultiple>true false </AllowMultiple> If this field is set to avalue of “false”, will only return the first Contact Method that meetsyour criteria.

Major Objects—Distribution List: a Distribution List is a grouping ofContact Methods. It allows a member to send a message to all of theContact Methods in that list. A Distribution List object may containsome or all of the following fields:

TABLE 11 Distribution List Major Object Fields Fields Description In/OutAllowed Values Example Command Indicates the desired action. Options InMust include one of <Command>append (Required) include: the followingvalues: </Command> Create (Create a Distribution List) create Replace(Replace existing Contact replace Methods in this list with the Contactappend Methods contained in this request) delete Append (Add ContactMethods to the remove existing list) Delete (Delete Contact Methods fromthe list) Remove (Remove the whole Distribution List) Name Unique namefor Distribution List In When creating a list, <Name>Gryffindor</Name>give it a unique name; for example, “Gryffindor” (32 character limit).NOTE: When using any other command option, you must enter either Name orId field to identify the Distribution List Description Descriptive textabout the list In Optional field <Description>GryffindorHouse</Description> Id Unique identifier for the List In/Out If thevalue of the <Id>k431k45</Id> Command field is create, no Id field isrequired, if any other value, enter a value for either Name or Id field

In addition, the Distribution List object must have a list of ContactMethodRef sub-objects (i.e., pointers to already-created Contact Methodobjects). An exemplary Distribution List object is as follows:

-   <Distribution List>    -   <Command append</Command    -   <Name>Gryffindor</Name>    -   <ContactMethodRef>        -   <LastName>Potter</LastName>        -   <Transport>email</Transport>    -   </ContactMethodRef>    -   <ContactMethodRef>        -   <Id>kkk3btkk</Id>    -   </ContactMethodRef>    -   </Distribution Lists

Major Objects—Job: a Job object contains a message to one or moreContacts using one or more Contact Methods, and contains sub-objectsthat define the specifics of the messaging task (e.g., the sender, thebody of the message, recipients, etc.) A Job object also contains atleast one Message sub-object (described below), and one or more DeliveryRequest or Contact sub-objects.

A Job object contains only two fields, and these are specified only in aResponse:

TABLE 12 Job Major Object Fields Fields Description In/Out All wedValues Example Id Identifier for this Job Out <Id>kkk3btkk</Id> ChargesEstimated cost of this Out Floating point number <Charges>1.60</Charges>Job

Major Objects—Job—Sub-objects—Message: the Message sub-object specifiesthe actual message. It includes fields and optional MessageArg Objects,and allows the requester to specify delivery times.

TABLE 13 Job Major Object Message Sub-object Fields Fields DescriptionIn/Out All wed Values Example Subject field The “Subject” line of the InThe actual text of your <Subject > <![CDATA (Required) message message.[Friday's sales meeting is cancelled.]]> </Subject> Template In<Template>generic (optional) </Template> field Id Unique identifier forthis Out <Id>kkk171bj4</Id> Message sub-object Date Marks the date andtime Out <Date>1999:10:20 the message was 19:14:39</Date> submittedDeliveryTime Marks the requested time In <DeliveryTime>1999:10:20 ofdelivery 19:14:39</DeliveryTime> DeliveryTime Options related to the InStartingAt or TryToFinishBy <DeliveryTimeModifer> Modifier requesteddelivery time StartingAt</DeliveryTime Modifier>

Major Objects—Job—Sub-objects—Message—MessageArg Sub-objects: a Messageobject contains one or more MessageArg sub-objects that consist of aseries of Name/Value tags according to the following syntax:

-   -   <MessageArg>        -   <Name>SENDER</Name>        -   <Value>Hermione Grainger</Value>    -   </MessageArg>

The optional MessageArg Name/Value tags are as follows:

TABLE 14 Job Major Object Message Sub-object MessageArg Sub-object TagsLegal Name Values Description Example SENDER Character The sender's<MessageArg> string (member) name. It is <Name>SENDER</Name> used in theFrom field <Value>Oliver Wood</Value> for all methods of </MessageArg>transport except email. BODY Character The actual text of the<MessageArg> string message. This text <Name>Body</Name> should beenclosed in <Value< >![CDATA CDATA tags. [I have scheduled an extraQuidditch practice session before the match with Slytherin. Be thereWednesday at 8:00 AM sharp.]]> </Value> </MessageArg> ASK_YESNO_QUESTIONYES If a yes/no question is <MessageArg> NO asked, this should be<Name>ASK_YESNO_QUESTION</Name> set to YES, otherwise <Value>YES</Value>NO; for example </MessageArg> QUESTION_TO_ASK If the <MessageArg>ASK_YESNO_QUESTION <Name> <QUESTION_TO_ASK</Name> field is set to<Value> <![CDATA YES, use this field to [Can you make the practicesession?]]> enter the actual text of </Value> the question.</MessageArg> EMAIL_ADDR The email address that <MessageArg> is used inthe From <Name>EMAIL_ADDR</Name> and Reply-to fields <Value><![CDATA[wood@Hogwarts.edu]]> when sending a </Value> message via email.</MessageArg>

An exemplary Job Object is as follows:

-   <Job>    -   <Message>    -   <Subject>Extra Quidditch Practice</Subject>    -   <Template>generic</Template>        -   <MessageArg>            -   <Name>SENDER</Name>                -   <Value>Oliver Wood</Value>        -   </MessageArg>        -   <MessageArg>            -   <Name>BODY</Name>            -   <Value><|[CCDATA[                -   I have scheduled an extra Quidditch practice session                    before the match with Slytherin. Be there Wednesday                    at 8:00 AM sharp.                -   ]]>            -   </Value>        -   </MessageArg>        -   <MessageArg>            -   <Name>ASK_YESNO_QUESTION</Name>            -   <Value>YES</Value>        -   </MessageArg>        -   <MessageArg>            -   <Name><QUESTION_TO_ASK</Name>                -   <Value><|[CCDATA[                -    Can you make the practice session?]]>                -   </Value>        -   </MessageArg>        -   <MessageArg>            -   <Name>EMAIL_ADDR</Name>            -   <Value><|[CDATA[wood@Hogwarts.edu]]>            -   </Value>        -   </MessageArg>-   </Message>-   <Contact>    -   <FirstName>Harry</FirstName>    -   <LastName>Potter</LastName>    -   <ContactMethod>        -   <Transport>email</Transport>        -   <EmailAddress>potter@hogwarts.edu</EmailAdddress>    -   </ContactMethod>-   </Contact>-   <DeliveryRequest>    -   <ContactMethodRef>        -   <LastName>Weasley</LastName>        -   <Transport>email</Transport>    -   </ContactMethodRef>-   </DeliveryRequest>-   </Job>

Major Objects—Job—Sub-objects—Delivery Request: the Delivery Requestsub-object allows the requester to specify a recipient for a job, aswell as to specify delivery options (as fields within the sub-object).The Delivery Request Object may contain a Contact MethodRef sub-object(to refer to a previously created contact method for the recipient) ormay instead refer to a Contact sub-object of a Job object (for one-timeuse of that Contact/Contact Method).

An exemplary Delivery Request sub-object is as follows:

-   <DeliveryRequest>    -   <ContactMethodRef>        -   <LastName>Potter</LastName>        -   <Transport>email</Transport>        -   <Qualifier>home</Qualifier>    -   </ContactMethodRef>-   </DeliveryRequest>

The Delivery Request sub-object is also returned by API 145 as aResponse. Furthermore, when an existing Job object is retrieved using aRange object lookup (described below), that job's Delivery Requests arealso returned.

The Delivery Request sub-object may contain the following fields:

TABLE 15 Job Major Object Delivery Request Sub-object Fields AllowedFields Description In/Out Values Example DeliveryOptions Sets thedelivery options In standard <DeliveryOptions>standard urgent</DeliveryOptions> Id Unique identifier for this Delivery Out<Id>kkk224524</Id> Request EstDuration Returns length of time, inseconds, that Out Integer <EstDuration>80 server estimates it will be onthe phone </EstDuration> during this delivery EstSize Estimated numberof pages in a fax, if it Out Integer <EstSize>3</EstSize> was a faxStatus Returns delivery status of the message for Out Not Sent<Status>SENT</Status> this Delivery Request: Sent Not Sent (ThisDelivery Request has not Failed yet been delivererd.) Cancelled Sent(This Delivery Request has been Cancel successfully delivered.) PendingFailed (The final attempt at delivery failed.) Cancelled (Your DeliveryRequest was cancelled.) Cancel Pending (Your Delivery Requestcancellation is pending.) Details Gives the following information aboutthe Out See <Details>Modem</Details> status of the current deliveryattempt: Description Bad Address Delivery Address is unreachable (Nofurther attempts will be made.) No Answer (another delivery may beattempted.) Busy (another delivery may be attempted.) Answering Machine(assumed) (phone message delivered, no further attempts will be made)Answering Maching (phone message delivered, no further attempts will bemade) Maximum Delivery Attempts Exceeded (No further attempts will bemade.) Acknowledged (message delivered; if phione, the personacknowledged by pressing 1. No further attempts will be made.) Modem (Nofurther attempts will be made.) Hangup (Call was dropped before messagecould be delivered, may attempt another delivery.) Callback Later(Message recipient elected a later callback, another delivery will beattempted.) Internal Error (internal error encountered, may attemptanother delivery.) Completed True if no further delivery attempts willOut true <Completed>true be made for this delivery request. false</Completed>

An exemplary Delivery Request Response is as follows:

-   -   <DeliveryRequest>        -   <ID>kztubkkkk</ID>        -   <EstDuration>80</EstDuration>        -   <Status>Not Sent</Status>        -   <DeliveryOptions>Standard</DeliveryOptions>        -   <Completed>false</Completed>        -   <ContactMethod>            -   <ID>kit5bkkuk</ID>            -   <Transport>phone</Transport>            -   <Qualifier>office</Qualifier>            -   <Unreachable>false</Unreachable>            -   <EmailAddress>potter@hogwarts.edu</E mailAddress>        -   </ContactMethod>        -   <Contact>            -   <ID>kk36bkkkk</ID>            -   <Prefix></Prefix>            -   <FirstName>Harry</FirstName>            -   <MiddleName></MiddleName>            -   <LastName>Potter</LastName>            -   <Company>Hogwarts School for Witchcraft and                Wizardry</Company>            -   <Title>Student</Title>            -   <OneTime>true</OneTime>        -   </Contact>    -   </DeliveryRequest>

Major Objects—Job—Sub-objects—Delivery Request—Delivery Sub-object: theDelivery sub-object never appears in a Request. It is returned by API145 as a sub-object of a Delivery Request object when a Range objectlookup (see below) is performed on a job.

The Delivery sub-object may contain the following fields:

TABLE 16 Job Major Object Delivery Request Sub-object DeliverySub-object Fields Allowed Fields Description In/Out Values Example IdUnique identifier for this Delivery Out <Id>kkk224524</Id> TimestampTime delivery was made Out Integer <Timestamp>2000:06:0504:15:22</Timestamp> Duration Returns length of time, in seconds, thatOut Integer <Duration>80</Duration> server was on the phone during thisdelivery. Status Returns delivery status of the message for Out Not Sent<Status>SENT</Status> this Delivery. Sent Not Sent (This DeliveryRequest has not Failed yet been delivererd.) Cancelled Sent (ThisDelivery has been successfully Cancel delivered.) Pending Failed (Thefinal attempt at delivery failed.) Cancelled (Your Delivery wascancelled.) Cancel Pending (Your Delivery cancellation is pending.)Details Gives the following information about the Out<Details>Modem</Details> status of this delivery attempt: Bad AddressDelivery Address is unreachable (No further attempts will be made.) NoAnswer (another delivery may be attempted.) Busy (another delivery maybe attempted.) Answering Machine (assumed) (phone message delivered, nofurther attempts will be made) Answering Maching (phone messagedelivered, no further attempts will be made) Maximum Delivery AttemptsExceeded (No further attempts will be made.) Acknowledged (messagedelivered; if phone, the person acknowledged by pressing 1. No furtherattempts will be made.) Modem (No further attempts will be made.) Hangup(Call was dropped before message could be delivered, may attempt anotherdelivery.) Callback Later (Message recipient elected a later callback,another delivery will be attempted.) Internal Error (internal errorencountered, may attempt another delivery.) Size Number of pages in afax, if it was a fax Out standard <Size>3</Size> urgent Cost Actual costfor this delivery in US Dollars Out Floating <Cost>18.20</Cost> pointvalue

Major Objects—Range: The Range object facilitates retrieval of a list ofobjects based on specified criteria. In particular, the Range object canretrieve Distribution List, Job, and Contact objects. The Response to aRange object returns the requested objects.

The Range Major Object may contain the following fields:

TABLE 17 Range Major Object Fields Fields Description In/Out AllowedValues Example Object Specifies the type of object you In DistributionList <Object> are trying to look up Job DistributionList Contact</Object> Member Type Specifies criteria for the In If <Object> value is<Type>Name</Type> lookup; depend on the value Distribution List: of<Object>: Name (look up by Name field) Distribution List Id (look up byId field) Job All (return all Dist. Lists for Contact this Member)Member Job: Date (look up by date) Id (look up by Id) All (return allJobs for this Member) Contact: LastName (look up by LastName field) Id(lookup by Id field) Company (lookup by Company field) All (return allContacts for this Member) Member: Username (lookup by Username field) Id(lookup by Id field) Start Specifies criteria for the data In String If<Type>LastName</Type> you are looking up; depends Then, on the value of<Type> <Start>Potter</Start> If <Type>Date</Type> Then,<Start>2000:02:14 12:30:00</Start> End Specifies the end of a date Inyyyy:mm:dd:hh:mm:ss <End>2000:02:14 range; only used if the value of12:35:00</End> <Type> is “Date”

The Range object is always included in a Request object, with the valueof the RequestType set to “lookup.” The most common use for the Rangeobject is to look up a Job object by Id, for example,

-   -   <Range>        -   <Object>job<Object>        -   <Type>Id</Type>        -   <Start>kkky5btk</Start>    -   <Range>

Error Handling: Errors fall into three classes: parsing errors, fatalerrors, and errors/warnings encountered while validating any object orfield.

Parsing errors occur when the input XML tags do not conform to XMLspecifications. Typical examples of malformed XML code include tags thatare not closed and illegal characters; to avoid the latter type oferror, freeform text should be enclosed within CDATA tags. When parsingerrors are encountered, API 145 returns a ParseErrors object, whichcontains one or more sub-objects called ParseError and having thefollowing fields:

TABLE 18 ParseError Sub-object Fields Allowed Fields Description In/OutValues Example ErrorString Text explaining the error Out String<ErrorString>Expecting ‘a name’, found ‘?’</ErrorString> LineNumber Linenumber where error found Out Integer <LineNumber>0 </LineNumber>

An example is as follows:

-   -   <ParseErrors>        -   <ParseError>            -   <ErrorString>Expecting ‘a name’, found ‘?’,/ErrorString>            -   <LineNumber>9</LineNumber>        -   </ParseError>    -   </ParseErrors>

A fatal error signifies a significant problem encountered in the courseof processing a Request. API 145 returns a FatalError object with asingle field (ErrorString), which indicates the nature of the error. Forexample,

-   -   <FatalError>        -   <ErrorString>User Transaction Server            Unavailable.</ErrorString>    -   </FatalError>        Validation errors and warnings are attached to problematic        objects or fields as “attributes.” The Errors and Warnings        fields of a Response object contain the following information:

TABLE 19 Response Super Object Errors and Warnings Fields Allowed FieldsDescription In/Out Values Example Errors Set to the number of errorsdiscovered Out Unsigned <Errors>2</Errors> while processing the majorobjects integer included in the Request Warnings Set to the number ofwarnings (a less Out Unsigned <Warnings>1</Warnings> severe error)discovered while integer processing the major objects included in theRequest

Table 19 Response Super Object Errors and Warnings Fields

For example, if a Request contains an invalid telephone number, awarning attribute will be attached to the problematic <PhoneNum> field.If a Request fails to provide a Billing sub-object when trying to add aMember, an error attribute will be attached to the Member object.

It will therefore foregoing represents a full-featured messaging systemcapable of operating in multiple communication modes and interactingwith remote applications through a common, extensible interface. Theterms and expressions employed herein are used as terms of descriptionand not of limitation, and there is no intention, in the use of suchterms and expressions, of excluding any equivalents of the featuresshown and described or portions thereof, but it is recognized thatvarious modifications are possible within the scope of the inventionclaimed.

1. Apparatus comprising: a messaging application program interface(API), a network interface, a messaging facility, and remote enterpriseapplications, the API and network interface interfacing the messagingfacility with the remote enterprise applications; plural sendercomputers, each of the plural sender computers comprising a messagecompose mechanism to compose a message and compose a correspondingdesignation, the corresponding designation comprising destinationinformation identifying (i) a set of multiple human recipients and (ii)different modalities for transmitting the message to respective ones ofthe multiple human recipients; the API comprising a message anddesignation receive mechanism to receive, from the remote enterpriseapplications via the network connection, the message and correspondingdesignation; and the API comprising a messaging facility directionmechanism to direct the messaging facility to effect transmission ofeach of the messages to their corresponding destinations in accordancewith their corresponding designations.
 2. The apparatus according toclaim 1, wherein the message comprises all content of a message to bedelivered.
 3. The apparatus according to claim 2, wherein the remoteenterprise applications are coupled to the messaging facility via theInternet through the network interface.
 4. The apparatus according toclaim 3, wherein the API comprises an API portion of a messagingfacility processing platform.
 5. The apparatus according to claim 4,wherein the messaging facility processing platform comprises a server.6. The apparatus according to claim 4, wherein the network connectioncomprises an Internet connection.
 7. The apparatus according to claim 6,wherein the Internet connection is part of the network interface formingpart of the messaging facility processing platform.
 8. The apparatusaccording to claim 6, wherein the messaging facility processing platformcomprises a server.
 9. The apparatus according to claim 7, wherein thedifferent modalities comprise, for each individual recipient of the setof multiple recipients, a set of corresponding modalities fortransmitting the message to the individual recipient.
 10. The apparatusaccording to claim 9, wherein the different modalities comprise at leasttwo of email, fax, voice telephone, and pager.